/*
 * Copyright 2002-2017 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import java.util.Iterator;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.ListableBeanFactory;
import org.springframework.beans.factory.NoSuchBeanDefinitionException;
import org.springframework.lang.Nullable;

/**
 * 多数是由能够提供自身维护的bean列表的工厂来实现的配置接口.
 * 增强了ConfigurableBeanFactory的功能,提供了解析和修改bean定义的方法,以及预先实现单例的功能.
 * 虽然这个接口是BeanFactory的子接口,但是并不意味着,这个接口能够在常规的编码中使用:还是需要坚持使用BeanFactory和ListableBeanFactory.
 * 这个接口只是在需要访问bean工厂配置方法的时候,供框架内部插件的使用.
 * <p>
 * <p>
 * Configuration interface to be implemented by most listable bean factories.
 * In addition to {@link ConfigurableBeanFactory}, it provides facilities to
 * analyze and modify bean definitions, and to pre-instantiate singletons.
 * <p>
 * <p>This subinterface of {@link org.springframework.beans.factory.BeanFactory}
 * is not meant to be used in normal application code: Stick to
 * {@link org.springframework.beans.factory.BeanFactory} or
 * {@link org.springframework.beans.factory.ListableBeanFactory} for typical
 * use cases. This interface is just meant to allow for framework-internal
 * plug'n'play even when needing access to bean factory configuration methods.
 *
 * @author Juergen Hoeller
 * @see org.springframework.context.support.AbstractApplicationContext#getBeanFactory()
 * @since 03.11.2003
 */
public interface ConfigurableListableBeanFactory
		extends ListableBeanFactory, AutowireCapableBeanFactory, ConfigurableBeanFactory {

	/**
	 * 忽略自动装配的时候指定的依赖:比如String类型,默认就不处理.
	 * Ignore the given dependency type for autowiring:
	 * for example, String. Default is none.
	 *
	 * @param type the dependency type to ignore
	 */
	void ignoreDependencyType(Class<?> type);

	/**
	 * 自动装配时,忽略指定的接口依赖.
	 * 通常会被应用在应用程序上下文通过其他途径注册依赖的时候,比如BeanFactory是通过BeanFactory来注入的,ApplicationContext是通过
	 * ApplicationContextAware来注入的.
	 * 不过,在默认的场景下,只有BeanFactoryAware是被忽略的,如果有更多的忽略依赖的类型,执行当前方法来实现.
	 * Ignore the given dependency interface for autowiring.
	 * <p>This will typically be used by application contexts to register
	 * dependencies that are resolved in other ways, like BeanFactory through
	 * BeanFactoryAware or ApplicationContext through ApplicationContextAware.
	 * <p>By default, only the BeanFactoryAware interface is ignored.
	 * For further types to ignore, invoke this method for each type.
	 *
	 * @param ifc the dependency interface to ignore
	 * @see org.springframework.beans.factory.BeanFactoryAware
	 * @see org.springframework.context.ApplicationContextAware
	 */
	void ignoreDependencyInterface(Class<?> ifc);

	/**
	 * 通过自动注入的值来注册一个指定的依赖类型.
	 * 针对factory或者是context的引用来说,本应该是能够自动注入其值的,但是他不会作为一个Bean定义在工厂里面.
	 * 举例来说,在bean所在的位置,将一个ApplicationContext类型的依赖解析为一个ApplicationContext的实例.
	 * 需要注意的是,在BeanFactory当中没有注册这种默认的类型,包括BeanFactory本身也是如此.
	 * <p>
	 * <p>
	 * Register a special dependency type with corresponding autowired value.
	 * <p>This is intended for factory/context references that are supposed
	 * to be autowirable but are not defined as beans in the factory:
	 * e.g. a dependency of type ApplicationContext resolved to the
	 * ApplicationContext instance that the bean is living in.
	 * <p>Note: There are no such default types registered in a plain BeanFactory,
	 * not even for the BeanFactory interface itself.
	 *
	 * @param dependencyType the dependency type to register. This will typically
	 *                       be a base interface such as BeanFactory, with extensions of it resolved
	 *                       as well if declared as an autowiring dependency (e.g. ListableBeanFactory),
	 *                       as long as the given value actually implements the extended interface.
	 *                       注册依赖的类型.通常是一个像BeanFactory之类的普通接口,如果声明他作为一个自动注入的依赖配置
	 *                       (就像ListableBeanFactory一样),那么只要给定的值真正实现了扩展接口,那么它的扩展就能够解析.
	 * @param autowiredValue the corresponding autowired value. This may also be an
	 *                       implementation of the {@link org.springframework.beans.factory.ObjectFactory}
	 *                       interface, which allows for lazy resolution of the actual target value.
	 *                       相对应的自动装配值,可以是一个ObjectFactory接口的实现,他允许对真正的目标值延迟解析.
	 */
	void registerResolvableDependency(Class<?> dependencyType, @Nullable Object autowiredValue);

	/**
	 * 确定指定的Bean是否符合自动注入的要求,是否能够被注入到持有该依赖类型的Bean中,这个方法也会去祖先工厂中寻找需要的值.
	 * <p>
	 * <p>
	 * Determine whether the specified bean qualifies as an autowire candidate,
	 * to be injected into other beans which declare a dependency of matching type.
	 * <p>This method checks ancestor factories as well.
	 *
	 * @param beanName   the name of the bean to check 用来检查Bean的名称
	 * @param descriptor the descriptor of the dependency to resolve 解析依赖的描述符
	 * @return whether the bean should be considered as autowire candidate 当前Bean是不是可以作为值用于自动注入.
	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name 没有找到指定名称的Bean.
	 */
	boolean isAutowireCandidate(String beanName, DependencyDescriptor descriptor)
			throws NoSuchBeanDefinitionException;

	/**
	 * 返回指定Bean已经备注册的Bean定义.允许访问它的属性值和构造参数值(可以在Bean后处理器中修改).
	 * 返回的Bean定义对象不能是Bean工厂中已经注册的原始定义的副本,换而言之,他在需要的情况下,应该转换为更详细的实现类型.
	 * 需要注意的是,这个方法只会从当前工厂来访问本地bean定义,而不会去考虑它的祖先工厂.
	 * <p>
	 * <p>
	 * Return the registered BeanDefinition for the specified bean, allowing access
	 * to its property values and constructor argument value (which can be
	 * modified during bean factory post-processing).
	 * <p>A returned BeanDefinition object should not be a copy but the original
	 * definition object as registered in the factory. This means that it should
	 * be castable to a more specific implementation type, if necessary.
	 * <p><b>NOTE:</b> This method does <i>not</i> consider ancestor factories.
	 * It is only meant for accessing local bean definitions of this factory.
	 *
	 * @param beanName the name of the bean 指定的Bean名称
	 * @return the registered BeanDefinition 已经注册的bean实例.
	 * @throws NoSuchBeanDefinitionException if there is no bean with the given name
	 *                                       defined in this factory
	 *                                       如果在当前工厂中没有找到指定名称的Bean定义就会抛出该异常.
	 */
	BeanDefinition getBeanDefinition(String beanName) throws NoSuchBeanDefinitionException;

	/**
	 * 返回由该工厂管理的所有Bean定义集合.
	 * 包含了bean定义名称以及手动注册的单例实例,在类似与通过Bean名称类型或者注解来检索的工作方式,Bean定义名称始终优先.
	 * Return a unified view over all bean names managed by this factory.
	 * <p>Includes bean definition names as well as names of manually registered
	 * singleton instances, with bean definition names consistently coming first,
	 * analogous to how type/annotation specific retrieval of bean names works.
	 *
	 * @return the composite iterator for the bean names view bean名称视图的中和迭代器
	 * @see #containsBeanDefinition
	 * @see #registerSingleton
	 * @see #getBeanNamesForType
	 * @see #getBeanNamesForAnnotation
	 * @since 4.1.2
	 */
	Iterator<String> getBeanNamesIterator();

	/**
	 * 清除合并锅的Bean定义的缓存,移除那些没有自个作为元数据缓存的数据.
	 * 该方法,通常在对原始Bean定义进行更改后进行触发.(比如在使用了BeanFactoryPostProcessor)之后.
	 * 需要注意的是,此时已经创建了的元数据将会被保留.
	 * <p>
	 * <p>
	 * Clear the merged bean definition cache, removing entries for beans
	 * which are not considered eligible for full metadata caching yet.
	 * <p>Typically triggered after changes to the original bean definitions,
	 * e.g. after applying a {@link BeanFactoryPostProcessor}. Note that metadata
	 * for beans which have already been created at this point will be kept around.
	 *
	 * @see #getBeanDefinition
	 * @see #getMergedBeanDefinition
	 * @since 4.2
	 */
	void clearMetadataCache();

	/**
	 * 冻结所有的Bean定义,表示注册的Bean定义不会被修改或者进一步的后置处理.
	 * 通过这一步操作,来允许工厂积极的进行缓存元数据.
	 * <p>
	 * <p>
	 * Freeze all bean definitions, signalling that the registered bean definitions
	 * will not be modified or post-processed any further.
	 * <p>This allows the factory to aggressively cache bean definition metadata.
	 */
	void freezeConfiguration();

	/**
	 * 返回当前工厂是不是被冻结了,也就说不允许修改Bean定义或者不允许进一步的执行后置处理了.
	 * <p>
	 * <p>
	 * Return whether this factory's bean definitions are frozen,
	 * i.e. are not supposed to be modified or post-processed any further.
	 *
	 * @return {@code true} if the factory's configuration is considered frozen
	 */
	boolean isConfigurationFrozen();

	/**
	 * 确保所有的非懒加载单例都被实例化,同样包括工厂Bean,如果需要的话,通常会在工厂设置完毕后执行.
	 * <p>
	 * <p>
	 * Ensure that all non-lazy-init singletons are instantiated, also considering
	 * {@link org.springframework.beans.factory.FactoryBean FactoryBeans}.
	 * Typically invoked at the end of factory setup, if desired.
	 *
	 * @throws BeansException if one of the singleton beans could not be created.
	 *                        Note: This may have left the factory with some beans already initialized!
	 *                        Call {@link #destroySingletons()} for full cleanup in this case.
	 *                        如果有一个单例Bean不能够被创建,注意,这可能是因为在当前工厂外,已经被其他工厂实例化了.这时候就要调用
	 *                        {@link #destroySingletons()}(销毁单例)方法来清理当前的缓存.
	 *
	 * @see #destroySingletons()
	 */
	void preInstantiateSingletons() throws BeansException;

}
